MuleSoft Accelerators - Setup Guide
Build environment
All Mule applications run under the Java Runtime Environment (JRE). Application components are built and deployed using Maven, a popular software management tool used in DevOps environments. MuleSoft also provides an Eclipse-based Integrated Development Environment (IDE) called Anypoint Studio, which is used for developing Mule applications in a graphical environment. While Studio can also be used for building, testing, and deploying applications, the instructions provided in the Accelerator documentation assume the use of Maven from the command line (except where noted).
Software requirements
The MuleSoft Accelerators for Salesforce Clouds are built on Mule 4 and Studio 7. Assets may work with other versions of Mule and Studio, but no assurances can be given. Here is a list of the minimum software requirements for working with Accelerator assets:
- Anypoint Studio 7.11.0 or higher
- Mule Runtime 4.3.0 or higher (included with Studio)
- Latest AdoptOpenJDK 8 release (included with Studio)
- Latest Maven 3.8.x release (for command-line deployments)
- Latest Postman 9.x release (for API testing)
Workstation setup
Perform the following steps to prepare your workstation for building, deploying, and testing Accelerator assets. These instructions assume some basic knowledge of using Maven and Eclipse-based products.
Installing
Download and install the latest 64-bit version of the OpenJDK 8 release from https://adoptopenjdk.net. On Windows, add or update the
JAVA_HOME
environment variable to point to the installation root directory (e.g., C:\Program Files\Java\jdk1.8.0_265) and append %JAVA_HOME%\bin to the PATH variable.Download and install the latest Apache Maven 3.8.x release from http://maven.apache.org/download.cgi. Add or update the MAVEN_HOME environment variable to point to the installation root directory (e.g., C:\Utilities\apache-maven-3.8.4) and append
%MAVEN_HOME%\bin
($MAVEN_HOME/bin
on Linux/MacOS) to the PATH variable.Download and install the latest 64-bit version of the Anypoint Studio 7 release from https://www.mulesoft.com/lp/dl/studio. Do not install the product under a folder containing spaces in the name.
Launch Studio and create a new workspace for the accelerator assets. Do not locate the workspace under a folder containing spaces in the name.
Configuring the Accelerator build
Download the Accelerator Common Resources asset from Exchange and unpack the archive to a temporary directory. The directory should contain a single Studio project folder called
accelerator-common-resources
.Import the project folder into Studio using the
General/Existing Projects into Workspace
wizard (not the Anypoint Studio project wizard). If the project does not import asaccelerator-common-build
, you can select the project in thePackage Explorer
view and pressF2
to rename it:Copy the contents of the
settings-accelerators.xml
file to your local Mavensettings.xml
file, which is usually located under$HOME/.m2
on Linux/MacOS hosts and%USERPROFILE%\.m2
on Windows hosts; create a new file if it does not exist. If the file already exists, make sure to merge the contents of thesettings-accelerators.xml
with the existing. You may also choose to keep the file separate and specify the-s <filename>
option when running Maven commands; in Studio you will also need to override the user settings path (underAnypoint Studio/Maven/User Settings
in the Preferences dialog). Note: This step is optional, if the project is intended to build only in Anypoint StudioFor now, update the
server
entries to specify your own usernames and passwords for the two Exchange repositories (anypoint-exchange-v2
andaccelerator-exchange
). If you want to run MUnit tests from the command line, you will also need to provide separate credentials for the MuleSoft Nexus EE repository (mule-enterprise
).
Testing the configuration
Having proper values in the Maven settings file is critical for being able to resolve, build and deploy components using Maven.
To verify your workstation setup, import any Accelerator implementation template asset into Studio. You can either manually download the asset from Exchange and import it using the Packaged mule application (jar)
wizard or you can launch the Exchange viewer in Studio to browse and open one directly.
Once the project has been imported, verify that the project name in Studio matches the name
element in the pom.xml
file. If it does not (which is usually the case when importing from a downloaded archive), press F2
to rename it accordingly; this will make it easier to use the build scripts later on. Ignore any warnings or errors for now.
Open your favorite shell and navigate to the project root folder (e.g., C:\workspaces\accelerators\accelerator-jira-sys-api
). Run the command mvn clean
. If the command completes successfully (the message BUILD SUCCESS
appears) then you are good to go. If any errors are reported, they must be resolved before continuing; consult the Troubleshooting section below for help with some common issues.
In Studio, close the project, wait until Studio has finished processing any tasks, and then open it again. Ensure the project builds with no errors.
Troubleshooting
If the mvn clean
command does not complete successfully, or if Studio reports errors for the imported project, something in your setup is either missing or incorrect. The following table provides some common issues that may be encountered along with some suggested resolution steps:
Issue | Possible Cause | Resolution |
---|---|---|
Maven cannot find one or more dependencies | Credentials provided for the server entries may be invalid; if they are correct, it is possible Maven cached an earlier attempt to download the dependencies | First verify your credentials and then add then run mvn clean -U to force Maven to update all dependencies. You can also force an update by removing cached dependencies from the .m2/repository folder. If all else fails, download the POM Parent and Common Core assets and install them locally as per the Additional customization page. |
Studio reports "null" version errors | Studio is not resolving the parent POM correctly | If the mvn clean command succeeded, close the project and then reopen it. If that does not work, try restarting Studio. As a last resort, delete the project (but not the files) from Studio and then re-import it. |
Error reported during project rename | Studio has locked one or more files | Verify the new project folder contains the same files as the old one. Close Studio, delete the old project folder, then launch Studio again. |
Studio reports "cannot import as Mule project" error | The wrong wizard was used to import the project | If the project still appears in the Package Explorer view you can ignore the error. If not, try the import again with a different import wizard. |
Cannot update connector versions using Studio | Accelerator assets use dependency management defined in the parent Maven config | To update the version of a dependency, either add a <version> tag directly to the application's pom.xml file or update the version in the parent and redeploy it; be sure to update the version of the parent POM, and to reference the new version in the application. |